C/C++ Interactive Reference Guide

home *** CD-ROM | disk | FTP | other *** search

/ C/C++ Interactive Reference Guide / C-C++ Interactive Reference Guide.iso / c_ref / csource5 / 305_01 / mandel.doc < prev next >

Wrap

Text File | 1990-02-14 | 76KB | 1,537 lines

DOCUMENTATION FOR EMANDEL, EJULIA, and EMDISPLAY These are powerful programs with many features. Please read this documentation and then print out a copy of the file CMDS.TXT for reference before attempting to use them. The file SAMPLE.DOC is intended to guide you step-by-step through your first use. In what follows, UNLESS OTHERWISE NOTED everything said about Emandel applies also to Ejulia. COPYRIGHT NOTICE These program (Emandel, Ejulia, and Emdisplay) are copyrighted by Dan Schechter, Route 1 Box 19, Amenia, North Dakota 58004. You may not sell them. However, you are encouraged to make copies of them and pass them on to friends. Please keep the set intact. The programs Emandel, Ejulia, and Emdisplay, along with this documentation file MANDEL.DOC, the file SAMPLE.DOC, the command summary CMDS.TXT, and the batch file WHOLE.BAT should all be passed along together. SHAREWARE NOTICE Shareware means that you can legally obtain a copy of a program at little or no cost and try it for as long as you like before deciding whether it is worth paying for. If you find these programs enjoyable, please send $20 to: Dan Schechter Route 1 Box 19 Amenia, North Dakota 58004 U.S.A. -------------------------------------------------------------------- HARDWARE REQUIREMENTS COMPUTER: IBM PC or compatible. Running MS-DOS 2.0 or later. MEMORY: Emandel will use all available memory. 640K is required for full-size frames. 512K should do quite well. 384K will allow you to use all the program's features, but only on reduced-size frames. GRAPHICS: Hercules monochrome graphics adapter (or compatible) is required. DISK DRIVE: Hard disk. Emandel can produce data files as large as 414K. Therefore it WILL NOT RUN on a system limited to 360K floppy drives. It will run on a 1.2 Mb drive, or a 720K 3 1/2 inch drive but the reading and writing of disk files will be SO EXTREMELY SLOW that I absolutely DO NOT RECOMMEND running Emandel without a hard disk. If you have a numeric coprocessor chip Emandel will use it. Otherwise Emandel will use software math, which is slower. -------------------------------------------------------------------- I have never tested Emandel with any memory-resident programs. It probably will not work with them because of the graphics. And besides, they take up valuable memory. -------------------------------------------------------------------- BACKGROUND: COMPLEX NUMBERS AND THE MANDELBROT SET An imaginary number is an abstract mathematical concept: a number that, when multiplied by itself, gives a negative value. Real numbers, by contrast, always give positive values when squared. An imaginary number is denoted in mathematics by the lower case letter "i". Thus 5i is the imaginary number that when multiplied by itself gives -25. Imaginary numbers exist only in the minds of mathematicians. A complex number is a number that has both a real component and an imaginary component. It is denoted by the addition or subtraction of a real number and an imaginary number. For example 17+5i is a complex number. Both the real and imaginary components of a complex number may have fractional parts. The complex number plane is a flat surface on which every point corresponds to a complex number. The "origin" is the point corresponding to 0+0i. A straight line through the origin represents the real axis. Another straight line through the origin and perpendicular to the first represents the imaginary axis. By convention, positive real numbers are to the right of the origin, negative real numbers are to the left of the origin, positive imaginary numbers are above the origin, and negative imaginary numbers are below the origin. To find a complex number on the plane, start at the origin and go right or left along the real axis the amount of the real component (depending on whether the real component is positive or negative). Then go up or down, parallel to the imaginary axis, by the amount of the imaginary component (depending on whether the imaginary component is positive or negative). To find the magnitude of a complex number, measure the distance from it to the origin. To add two complex numbers, add their real components to find the real component of the sum, and add the imaginary components to find the imaginary component of the sum. To multiply two complex numbers, use the following formula: (A+Bi)*(C+Di) = (A*C)-(B*D) + ((B*C)+(A*D))i This is the binomial expansion. Now consider a mathematical procedure, as follows: Take a complex number. Let's call it P for convenience. Multiply P by itself, and then add P to the result. Multiply that result by itself and then add P to the new result. Again, multiply the new result by itself and then add P. Do this over and over again. Each time you do one multiplication and one addition you have done one iteration. (Iteration means doing the same thing over and over again.) Keep track of the iteration count. A remarkable thing happens as you continue iterating. Either the magnitude of your complex number grows ever larger and larger, or else it remains ALWAYS BELOW 2. Either it "approaches infinity" (as mathematicians express it) or else it never exceeds 2. The fact just noted was discovered by Benoit Mandelbrot. Therefore the Mandelbrot set is the collection of those complex numbers that remain below two under the above iterative process. In order to find all these numbers we must perform the above iterative process on every point P within a given area of the complex number plane. (In fact, we are forced to compromise by selecting a finite number of points, spaced at even intervals, over some part of the plane. Emandel uses at most 338,688 points.) And we must keep track of the iteration count for each point. What makes the Mandelbrot set so fascinating is that being a "fractal" it remains infinitely complex regardless of how much you magnify it. It can provide you with an unlimited variety of amazing patterns. For further reading, see Scientific American magazine, August 1985, the Computer Recreations column by A.K. Dewdney. And for yet further reading, see THE FRACTAL GEOMETRY OF NATURE by Benoit Mandelbrot. The Julia sets (plural, since there are an infinite number of them) are related to the Mandelbrot set in that any point in or near the Mandelbrot set can serve as a "Julia point" for a distinct Julia set. Select a point and call it J. Then for every point P on the plane do the following: Square P and add J. Square the result and add J. Square the new result and add J again. And so on. As before, either the magnitude will approach infinity, or it will remain always below 2. Keep track of the iteration count of each point. Each Julia set will somewhat resemble the place in the Mandelbrot set from which you took point J. ------------------------------------------- EMANDEL Now we return to these programs: First we must select an arbitrary cut-off limit of iteration. 255 is a convenient number because it is the largest number that can be represented in one "byte" of computer memory. It also happens to work well when you begin exploring the Mandelbrot set. (As you go deeper into the set you will sometimes want to use higher cut-off limits.) In Emandel, the iteration cut-off is called "maxit", which is short for maximum iteration. When you run Emandel, it takes a portion of the complex number plane, and performs the iterative process I described above for each pixel (picture element) on the screen. If the magnitude of the point goes above 2, the program remembers how many iterations were performed for that pixel. If the magnitude is still below 2 after the number of iterations has reached maxit, the program goes on to the next pixel. Thus, when it is finished, every pixel has been assigned a value, from 1 to maxit. Pixels with a value of maxit are considered to be within the Mandelbrot set. Pixels with lower values are considered to be outside the set. During the calculation phase of the program, pixels inside the set are illuminated, and pixels outside the set are dark. Calculation can take anywhere from a few minutes to many days, depending on how large a portion of the screen you use, what part of the complex number plane you are in, the value you have assigned to maxit, and the speed of your computer. Now the fun begins. Every pixel has a value, and you and the computer must decide which pixels to illuminate. If you merely illuminate pixels whose values equal maxit, the pictures will be rather dull and flat looking. But Emandel allows you to specify many different ranges of values for illumination. For example, you might illuminate all pixels with odd-numbered values. Or you might illuminate pixels with values from 10 to 17 and from 25 to 100 and from 124 to 125. In Emandel, a range of iteration values is called a cluster. Each time you specify a cluster of values to be illuminated, Emandel re-draws the screen to show you the new pattern. Marvelous figures seem to appear out of nothing. You can change the values for a cluster, clear a cluster, or move on to another cluster. Emandel is intelligent enough to allow you to specify a group of clusters to be filled in in a regular way. (More on this later, in the section on Auto-draw.) When you have a picture you like, you can save it to a disk file. The program Emdisplay allows you to view it as well as print it out on an Epson-compatible dot-matrix printer. Because the calculation phase takes so long, Emandel allows you to break off calculation, store the data in a disk file, and exit from the program. Then you can resume later where you left off. I run Emandel at night while I sleep. Also, because calculation takes so long, "screen burn" would be a problem. Therefore Emandel allows you to blank the screen. And because the program is likely to run unattended for long periods, and you do not want the cat to inadvertently bollix it up when he walks across the keyboard, Emandel will not respond to most keyboard commands when the screen is blanked. -------------------------------------------------------------------- Emandel is run from the MS-DOS command line. This means you give it all its starting parameters when you tell DOS to run the program, rather than answering menu questions after the program starts. The following line will start the program and produce an over-view of the entire Mandelbrot set: EMANDEL -2.5 1.25 -1.25 /M100 /NWHOLE This line is contained in the batch file WHOLE.BAT. Thus you could just type: WHOLE to run the program for the first time. After that you never need to worry about the command line arguments because Emandel allows you to mark a portion of one picture to be enlarged for the next, and it will create a batch file to run itself. -------------------------------------------------------------------- Emandel has three operation modes: Main mode. Threshview mode. Grid Mode. Main mode is entered when you start the program. Main mode performs the arithmetic calculations and allows you to query the program concerning its parameters. Threshview mode is where you create and save patterns out of the program's raw data. You enter threshview mode from main mode. You can create partial patterns from a partial base of data, before the calculation is done, in order to get some idea of what you are getting. You can make as many pictures as you like from one frame. Each will have a different name, selected by the program. Your only limit is your available disk space. Exiting from Threshview mode will return you to main mode. Grid mode is where you mark a portion of the picture to be enlarged by the next run of the program. You position a box around the area you want enlarged, and Emandel produces the batch file to invoke itself. You can make as many batch files as you like in this way. Each will have a different name, selected by the program. You can enter grid mode directly from main mode or from threshview. Thus you can use threshview to make a pattern, and then use Grid to select a portion of that pattern for enlargement. Grid mode also gives you the coordinates and the value of any pixel on the screen. Exiting from Grid mode returns you to the mode you entered Grid mode from. -------------------------------------------------------------------- HOW TO EXIT FROM THE PROGRAM If the screen is blanked, press control-S. Press ESC several times. This will take you, one level at a time, from whatever part of the program you may be in, back to Main mode. Now press control-C to exit from the program. If you have not saved the data, the program will ask you "file not saved. Exit?". Press N to remain in the program. Press Y to exit from the program. THIS IS THE ONLY WAY TO EXIT FROM THE PROGRAM OTHER THAN A COLD BOOT. SO KEEP THESE INSTRUCTIONS HANDY UNTIL YOU ARE FAMILIAR WITH THEM. -------------------------------------------------------------------- GENERAL OPERATING INSTRUCTIONS STARTING EMANDEL FROM THE COMMAND LINE Items enclosed in angle brackets < > are named parameters. Enter them without the brackets. Items enclosed in square brackets are optional. Enter them without the brackets, or leave them out entirely. EMANDEL <lr> <ti> <bi> [/M<maxit>] [/A<asp>] [/S<size>] [/X] [/B<beep>] [/N<name>] EJULIA <lr> <ti> <bi> <rj> <ij> [/M<maxit>] [/A<asp>] [/S<size>] [\X] [/B<beep>] [/N<name>] EMANDEL <filename> EJULIA <filename> In the first and second examples above, Emandel and Ejulia are started for a new frame. In the third and fourth examples above, Emandel and Ejulia are started with an already-existing data file, which may be from an interrupted session, or may be a completed data file that you wish to use for Threshview or Grid. REQUIRED PARAMETERS <lr> is a floating point number, the real coordinate of the left edge of the frame. <ti> is a floating point number, the imaginary coordinate of the top of the frame. <bi> is a floating point number, the imaginary coordinate of the bottom of the frame. <rj> (EJULIA only) is a floating point number, the real coordinate of the Julia point. <ij> (EJULIA only) is a floating point number, the imaginary coordinate of the julia point. Floating point numbers may be decimal fractions such as 1.2345 or 0.1234. They may be positive or negative. Or they be entered in "scientific" notation. Such as -.9876e-3 which means negative .9876 divided by ten to the 3rd power. Note that there may not be any spaces within the number. For practical purposes, ti and bi should be between 1.5 and -1.5, ti should be greater than bi, lr should be between -2.5 and 1.0, and the Julia point should be near the edge of the Mandelbrot set. Many starting parameters will result in empty frames, which is why it is best to begin with the whole set and use Grid mode to enlarge successively smaller areas. <filename> (In the third and fourth examples above) is the name of a data file with the file type extension PIK. If you give a file name without a file type extension, or with a different file type extension, the file type extension PIK will be used regardless. COMMAND LINE OPTIONS <maxit> (see below) is an integer from 1 to 1023. For practical purposes you will probably never set maxit lower than about 50. Default is 255. <asp> (see below) is a positive floating point number. Default is .75 and typical values might range from 0.1 to 10.0 <size> (see below) is a positive decimal fraction, less than or equal to 1. Default is 1. <name> (see below) is the name you wish the data file to have. ASP. Aspect ratio. The vertical-to-horizontal ratio of the screen is .75. This is the default aspect ratio. Sometimes you may want to make a tall narrow picture, or a wide squat picture. You can do this by changing the aspect ratio. On the command line put a forward slash, followed by the letter A followed by a number. (No spaces.) For example /A1 will produce a square picture. SIZE. Size is the fraction of total screen area actually used. 1 is the full screen. .5 is half the screen area. You will sometimes want to use a small part of the screen to make a frame in a hurry. Or if your computer has less than 640 K of memory you may have to use less than the full screen because of the memory-intensive nature of the program. /S.1 will get you one-tenth the screen area. INTERACTION BETWEEN SIZE AND ASPECT. Aspect ratio takes precedence. If you select an aspect ratio of 1 (for a square picture) then it is impossible for size to be 1. The screen is not square, so a square picture cannot fill it. If you select 1 for the aspect ratio and 1 for the size, the program will adjust size downward as necessary. On the other hand, if you select aspect ratio = 1 and size = .5 your picture will be a square and will have an area equal to half the total screen area, because a square of that size can fit into the screen. If you select a size and aspect ratio that requires more memory than your system has, the program will cut as much as necessary from the right-hand side of the frame. It will then inform you of the new size and aspect and ask if you want to proceed or abort. You may answer P to go ahead with the program's new values, or you may answer A and then start over with different values. You will not be able to get a larger picture area in this way, because that would require more computer memory. But you may be able to get a more satisfactory picture shape by specifying a smaller value of size. MAXIT. You can specify the maximum iteration cut-off value. On the command line, put a forward slash, followed by the letter M, followed by a number from 1 to 1023. Values much below 100 will not produce satisfactory results in most cases. /M300 will get you maxit = 300. A NOTE ON MAXIT AND MEMORY USAGE. Because 255 is the largest value that can fit in an 8-bit "byte", Emandel has to operate slightly differently when maxit is set higher than 255. It will require almost 25% more memory, and will cause a *slight* slow-down in program operation. Thus, if you have limited memory (especially on 384K systems) you will not be able to make as large a picture if maxit is greater than 255 as you will be able to make if maxit is less than or equal to 255. FILENAME. Emandel will let you choose a file name for the data file, or it will pick one itself. The file type extension is always PIK. You cannot change that. If it picks a name itself, it will consist of the letters "EM" (or "EJ" for Ejulia) followed by a number, and then the extension "PIK". The number will be selected so that it does not conflict with any file already on the current logged directory. If you wish to specify the name yourself, on the command line put a forward slash, followed by the letter N, followed by the name (no spaces). Thus /NMYPIC would result in the file name MYPIC.PIK. If you specify the file name in this way, Emandel will overwrite any existing file of the same name. All of these options can be selected and specified from within the Grid mode of Emandel, as it makes a batch file automatically. Aspect is determined by the shape of the box you create, and the others you can tell the program in response to the questions it will ask you. Generally, pressing ENTER (or RETURN) at a prompt causes the program to leave that parameter unchanged. (In the case of file name, it tells the program to pick a non-conflicting file name at run time, and in the case of size it sets size equal to 1.) /X is the auto-exit switch. (This also may be toggled from within the program.) Auto-exit tells the program to save data and exit immediately upon completion of calculation. If Emandel is entered with auto-exit enabled, the screen will automatically be blanked, just as though you had used the ^S command. This makes it possible to run Emandel from within your own batch file. Auto-exit will blank the screen on entry (to avoid screen burn) and will exit on completion so that your batch file regains control. Note that if there is insufficient memory on entry to the program and auto-exit is enabled, the program will exit immediately. This is to prevent a hang-up on unattended operation. The frame will not be automatically sized down without your approval. <beep> is the beeper alarm setting, which may be from 1 to 9. You can also set or change this from within the program. This is the number of times the console will beep on completion of calculation. Default is zero. -------------------------------------------------------------------- NOW YOU KNOW THE REASON FOR EMANDEL, AND HOW TO START IT, AND HOW TO EXIT FROM IT. NOW FOR A DISCUSSION OF ITS RUN-TIME FEATURES: -------------------------------------------------------------------- Any time a letter is preceded by a carat (^) it means that you hold down the CONTROL key while you tap the letter. <CR> stands for "carriage return." It means the ENTER or RETURN key. ESC stands for the ESCAPE key. <BS> stands for the BACKSPACE key. Note that this is not the same as the left arrow key. <Home> 7 on the number pad. <PgUp> 9 on the number pad. <End> 1 on the number pad. <PgDn> 3 on the number pad. <UA> 8 on the number pad. <LA> 4 on the number pad. <DA> 2 on the number pad. <RA> 6 on the number pad. EMANDEL DOES NOT REALLY USE THE ARROW KEYS: Rather, it uses the number pad keys which (on standard IBM keyboards) have arrows on them. Emandel sets the NumLock automatically upon entry to Grid mode. This means that IF YOU HAVE AN "ENHANCED" KEYBOARD with separate arrow keys, YOU MUST USE THE NUMBER KEYS, NOT THE SEPARATE ARROW KEYS. The reason for this is there are only 4 arrow keys, but Emandel (in Grid mode) needs 9 directional keys: 8 directions plus a stop key (5). -------------------------------------------------------------------- MAIN COMMANDS ^S Blank or restore the screen. To prevent screen-burn, and to reduce the likelihood of an unattended run being inadvertently interrupted, you can blank the screen with this command. No other command will affect the program while the screen is blanked. Pressing ^S a second time will restore the screen and enable all the other commands. ^Q Quit calculation. As a safety feature you must quit calculation before you can exit the program. This command has no effect if the program has finished calculating. ^U Resume calculating after the above command. This also has no effect if calculation has finished. ^E If this command IMMEDIATELY precedes ^C it will force the program to return a non-zero exit code to the system. The result of this is that the conditional command "IF ERRORLEVEL" (used in batch files) thinks the program has exited on an error. This command therefore can be used to prevent Emandel's self-produced batch file from erasing itself. ^C Exit from the program. (You must have previously used ^Q to quit calculation mode if calculation has not yet finished.) ^L Log new disk drive or subdirectory. You will be prompted to enter a new path. Use normal MS-DOS drive and path specifications. Entering an invalid subdirectory will have no effect. But BEWARE: logging a drive that does not have a disk in it can cause the program and the operating system to crash, because MS-DOS will dump the program without restoring the graphics card to text mode. ^W Write the program data to a disk file. This may be the data from a completed run, or it may be the data from a run that you wish to interrupt and save for later resumption. <space bar> The space bar will erase whatever is on the prompt line. ^G Enter Grid mode. Use Grid mode if you want to select a portion of the picture for enlargement in a later run. You can also use grid mode to see the value and coordinates of any pixel. ^T Enter Threshview mode. Use Threshview mode to create pictures after Emandel has calculated the pixel values. You may run Threshview on an incomplete frame to see what has developed so far. ^B Set or change the beeper-alarm. This may be set to any value from zero to 9. The computer will beep this many times when calculation has completed. If set to zero, it is disabled. ^R This will produce a batch file to run Emandel with EXACTLY the same parameters as in the present run. ^O (letter oh, not zero) While Grid mode allows you to delineate a small portion of the screen for the next run of Emandel, you may sometimes want to produce an overview of the present screen. That is, you want to reduce the size of the present picture, to see what surrounds it, rather than enlarge a small portion. The ^O command produces a batch file for an overview of the area surrounding the present frame. You will be asked for an expansion factor, which must be a whole number equal to or greater than 1. Using 1 is the same as the command ^R above, except that with ^O you will be able to enter a new file name, size, and maxit, whereas with ^R the present file name and all settings are used again. ^X Toggle auto-exit mode. When auto-exit is ON, Emandel will save the data file and exit as soon as calculation is completed. Thus you can run Emandel unattended as part of a larger batch file. ? The question mark is for help and to query the program. It must be followed by another keystroke, as follows: ?C Gives the coordinates of the present frame. Lr is the real component of the left edge of the frame. Ti is the imaginary component of the top of the frame. Bi is the imaginary component of the bottom of the frame. Rr is the real component of the right edge of the frame. ?M Gives the value of maxit, which is the maximum iteration cut-off value. ?H Gives the number of vertical scan lines computed so far. ?I Gives the amount of the numerical increment from one pixel to the next. This value gets smaller with increasing magnification. When this figure gets down around 0.000000000000001 (1.0e-15) you are approaching the limits of the ability of Emandel to perform meaningful calculations. This is because Emandel uses 64-bit arithmetic (about 15 decimal places). Consider these two numbers: 1.555555555555555 and 1.555555555555556. With 15-digit precision, it is impossible to distinguish between them because subtracting them gives a value of zero. ?S This will tell you some figures relating to the size and aspect ratio of the present frame: yl (y-limit) is the number of pixels vertically. xl (x- limit) is the number of pixels horizontally. (h and w, standing for height and width are the previous figures increased to the nearest 4-line or byte boundaries, and relate to the amount of memory the frame requires.) Size is the fraction of total screen area being used by the present run. 1 is maximum. On computers with less than 640K of memory it may be necessary to set size less than 1 because of memory limitations. asp is the aspect ratio. .75 is the aspect ratio of the full screen. Smaller values of asp indicate a picture that is wide and squat. Larger values of asp indicate a picture that is tall and narrow. (Emandel will adjust size as required, whether because of memory restriction, or because of conflict with asp.) Note that while the HGA has 348 horizontal scan lines, Emandel uses 504 scan lines in order to produce high-quality images for the Epson printer. On the screen, every third scan line is removed in order to fit the image into the available space. Because of the dot ratio of the HGA and the dot ratio of the printer, pictures remain the same shape when printed as they appear on the screen. But the printed images have slightly better resolution. ?G Gives the magnification factor of the present frame. This is figured with reference to a frame where Ti = 1.5 and Bi = -1.5. ?J Gives the coordinates of the "Julia point." This is the point used for calculating Julia sets. This command functions only in Ejulia, and has no effect in Emandel. ?P Gives the present disk drive and subdirectory path. ?% This tells you the approximate percentage of the frame which has been completed so far. The figure is truncated to the next lower integer. Thus if 37.9% of the frame has been completed, this command will show 37%. ?T This will show you three time figures. The first is how much time the program has spent in calculation phase during the present session. The second is how much time has been spent in calculation phase altogether on the present frame. (The two figures are different if you have used more than one program session on the present frame.) Time spent in Threshview mode, in Grid mode, or reading the help screens is not counted. The third figure is a VERY ROUGH approximation of the time it will take to complete the frame. If less then 10% of the frame has been completed, or if the average time per vertical scan line is less than 3 seconds, Emandel will not attempt to extrapolate a completion time, and will show an ellipsis [...] instead. The estimated completion time will be very inaccurate if the frame has a lot of high-value pixels on the left and a lot of low-value pixels on the right, or the other way around. It will be reasonably close if the frame has a relatively uniform mix of pixel- values across its width. This figure is only intended as a crude approximation. ?N This will tell you the name of the present file. ?B This tells you the value assigned to the beeper-alarm. ?X This tells you the status of the auto-exit feature. ?? This shows you the help screens. There are 5 help screens, covering various parts of the program. The help screens are NOT intended as a complete manual. They only contain a brief summary of the commands. -------------------------------------------------------------------- COMMANDS AVAILABLE IN THRESHVIEW MODE ESC Exit from Threshview mode. <BS> Pressing the BACKSPACE key while the screen is being re-drawn will interrupt the re-draw so that you may fill more clusters without waiting for the complete re-draw. V <CR> This will show you the values assigned to each of the clusters. Because there are hundreds of clusters, and the prompt line is only 90 characters wide, this command will show you one line at a time and wait for you to press a key. Pressing any key will show you the next line. Pressing ESC will by-pass the rest of the display and take you directly back to the "Cluster?" prompt. Display concludes if all remaining clusters are clear. So using the low-end clusters first will save time. L <CR> Log new drive or subdirectory. Same as ^L in the main commands. G <CR> Enter Grid mode. Same as ^G in the main commands. W <CR> Write a disk file of the picture presently on the screen. This is NOT the same as ^W in the main commands. ^W in main writes a file of the entire base of data for the present frame. That can be as large as 414K, depending on the parameters. This present command only writes a file of the image you see. This is never larger than 43K, and may be much smaller, depending on the value of "size." It is these image files that are used by Emdisplay to produce pictures on a dot-matrix printer. A <CR> Enter Auto-draw mode. Use this command when you want to assign a regular series of values to a sequence of clusters. R <CR> This will re-draw the screen. Use it when you have used <BS> to interrupt a re-draw, and then changed your mind and want to complete the re- draw. ? <CR> This will show you the help screens. It is the same as ?? in main. After you have selected a cluster, and Threshview asks you for the new top and bottom values you may enter, instead of a number: M This stands for the current value of maxit. < This stands for one less than the current value of maxit. = At the "Bottom" prompt this stands for top. At the "Top" prompt this stands for bottom, setting the one equal to the other. C This clears the present cluster. -------------------------------------------------------------------- AUTO-DRAW COMMANDS C (At the "Start?" prompt.) Clear all the clusters in the specified range. <CR> At the "First cluster?" prompt, <CR> means cluster 0, the lowest cluster. At the "Last cluster" prompt, <CR> means the highest cluster, which is cluster 300 on the present version of Emandel. At the "Start value", "size", or "gap" prompt, <CR> means 1. At the "Stop?" prompt, <CR> will set stop = maxit-1. ESC Abort auto-draw (If you realize you just entered a wrong value and you want to retract it.) -------------------------------------------------------------------- COMMANDS AVAILABLE IN GRID MODE ESC Exit from Grid mode. <space bar> Erase prompt line. + This increments the step size for cross-hair movement by one. * The asterisk increments the step size by ten. - (Minus sign) This decrements the step size by one. <BS> This sets the step size back to one. The above 4 step size commands also affect the step size of the box commands described later. <Del> Pressing the Del key toggles cross-hair motion back and forth between "glide" and "step" In "glide" mode, once you have pressed a direction key, the cross hairs will continue to move in the same direction until you press another direction key, or press 5 to stop movement. In "step" mode, you must continue to press a key if you wish movement to continue. 5 This stops the cross hairs. (And has no effect in step mode.) <Home> Moves the cross-hairs upward and to the left. <UA> Moves the cross-hairs upward. <PgUp> Moves the cross-hairs upward and to the right. <LA> Moves the cross-hairs to the left. <RA> Moves the cross-hairs to the right. <End> Moves the cross-hairs downward and to the left. <DA> Moves the cross-hairs downward. <PgDn> Moves the cross-hairs downward and to the right. All nine motion commands require that the Num-Lock be engaged. Emandel does this for you when you enter Grid mode, and disengages it when you leave Grid mode. Thus if your keyboard has a NumLock light you will see it go on and off. Remember that if you turn it off you will defeat the cross-hair motion commands. If you do this, simply turn it back on to restore operation. NOTE: If you have a keyboard with separate arrow and number pad keys, you must use the number-pad keys for cursor movement, rather than the arrow keys. ^B This opens a box or makes it bigger by one step ^S This makes the box smaller by one step. If you limit yourself to the two above box commands you will be certain that the aspect ratio of the box will be the same as the aspect ratio of the full screen. You should do this if you wish the largest possible pictures. The following commands change the shape of the box, and you may find the resulting picture does not entirely fill the screen. Aspect ratio takes precedence over size. Thus an aspect ratio of 1 (a square picture) cannot fill more than about 3/4 of the screen. ^D This moves the floor of the box down by one step. ^U This moves the floor of the box upward by one step. ^L This moves the right-hand side of the box left by one step. ^R This moves the right-hand side of the box right by one step. 0 (zero, not the letter oh) This closes the box. The following two commands cause Grid to produce a batch file. You will be asked to enter a file name for the new file. This will be the name for the next data file, not the name of the batch file. Pressing <CR> will cause Emandel to select a data file name at run-time. Then you will be asked to enter the value for maxit. Pressing <CR> will cause the same value of maxit to be used as is in effect in the present run. Then you will be asked to enter size. Size is a decimal number less than or equal to 1. 1 is full-size. Pressing <CR> will set size = 1. Size will be reduced at run-time if it conflicts with the aspect ratio or the available memory of your computer. You will not be asked for the aspect ratio. This is determined by the shape of the box you have made. Pressing ESC at any prompt will abort the batch file routine. # The cross-hatch causes a batch file to be written. Emandel will write a batch file that runs Emandel. Ejulia will write a batch file that runs Ejulia. ^J This command is for Emandel. It will have no effect in Ejulia. It will write a batch file that will run Ejulia to produce an entire Julia set, using the present cross-hair point as the Julia point. Remember that each Julia set is related to one point in the Mandelbrot set. This is the command that connects the two programs: It lets you select a point in the Mandelbrot set from Emandel, and then run Ejulia, producing an entire Julia set. From there, you use Ejulia, just as you used Emandel, to explore and magnify parts of the Julia set. There are an infinite number of Julia sets. The farther apart their Julia points are in the Mandelbrot set, the less alike the two Julia sets are. Generally, a Julia set will resemble the appearance of that part of the Mandelbrot set from which the point was taken. You will get the best results if you place the cross-hairs on a place where there is a lot of detail. -------------------------------------------------------------------- USING THRESHVIEW From main mode enter Threshview mode by pressing ^T. You will see a prompt that says "Cluster?" You now have several options: Press <ESC> to exit Threshview and return to main mode. Press L <CR> to log a different drive or subdirectory. Press V <CR> to view the present cluster values. Press G <CR> to enter Grid mode. Press W <CR> to write a disk file of the picture on the screen. Press A <CR> to use the Auto-draw feature. Press R <CR> to re-draw the screen. Press ? <CR> to see the help screens. Enter a number to indicate which cluster you wish to modify. Note that in the above commands you must use the <CR> after your command or after typing a number. You may use either upper case or lower case for the letter commands. If you select V a blinking cursor will appear at the end of the line. Press any key to continue. Press ESC to return directly to the "Cluster?" prompt. If you enter a number and press <CR> you will be shown the present bottom and top values of that cluster and asked for a new bottom value. Pressing <CR> at this point will cause the bottom value to be left unchanged. Entering a number will set the bottom value to that number. You will then be asked for a new top value. <CR> will leave the top value unchanged. Entering a number will set the top value to that number. Entering C <CR> at either "top" or "bottom" prompt will cause that cluster to be cleared. The bottom and top values may be equal. But specifying bottom above top will clear the cluster. Instead of entering numbers, you may enter the letter M. This causes the value to be set equal to the present value of maxit. Or you may enter a "less than" sign (<). This causes the value to be set to one less than maxit. This is useful when you want to leave the actual Mandelbrot set dark, but illuminate the pixels immediately outside it. Or you may enter an equals sign (=). This will set top equal to bottom or bottom equal to top. If all the clusters are clear, nothing will be done and you will be returned to the "Cluster?" prompt. However if any cluster contains valid values the screen will be re-drawn to show the picture specified by the clusters. If you press <BS> while the program is in the process of re-drawing the screen, the process will be halted and you will be returned to the "Cluster?" prompt. This allows you to set another cluster without waiting for the screen re-draw. Before Emandel begins to re-draw the screen it has to scan all the cluster values and set up an internal look-up table. This takes a short time. It begins with Cluster Zero, and it stops when no further clusters contain values. Thus you will get slightly faster operation if you use the low- numbered clusters first. That is, if you set clusters 1 through 50 it will take less time to set up the look-up table than if you set clusters 250 through 300. ------------------------------------------- USING AUTO-DRAW Auto-draw allows you to easily set a whole sequence of clusters in a specified pattern. This makes it easy, for example, to illuminate all pixels with even values, or values divisible by 3, etc. It is a labor-saving feature. At the Threshview "Cluster?" prompt, enter A <CR> (Note that you have to press the carriage return key (ENTER or RETURN) after the A.) Then, at the "First cluster?" prompt, enter the number of the first cluster in the sequence you wish to alter. If you just press <CR>, the first cluster will be cluster 0. If you press ESC no clusters will be changed and you will be returned to Threshview and the "Cluster?" prompt. At the "Last cluster?" prompt, enter the number of the last cluster you wish to alter. If you just press <CR> the last cluster will be the highest numbered cluster available, which is cluster 300 in the present version. If you press ESC no clusters will be changed and you will be returned to Threshview and the "Cluster?" prompt. At the "Start value?" prompt, enter the bottom value you wish the first cluster to have. If you enter C <CR> all the clusters in the specified sequence will be cleared. If you just press <CR> the start value will be set to 1. If you press ESC no clusters will be changed and you will be returned to Threshview and the "Cluster?" prompt. At the "Size?" prompt, enter the width you want each cluster to have. Because a cluster specifies a range of pixel values, "size" is the difference between the bottom value and the top value, plus one. If bottom = 15 and top = 16 then size is 2. If top and bottom are the same, then size is 1. <CR> will set the size to 1. ESC will abort, as above. At the "Gap?" prompt, enter the gap between clusters. Since each cluster specifies a range of pixel values to be illuminated, GAP is a range of pixel values to be left dark (unless those "dark" values are illuminated in a different cluster.) If gap is set at 1 and the top of one cluster is 17 then the bottom of the next cluster will be 19. If gap is 3 and the top of one cluster is 17 then the bottom of the next cluster will be 21. <CR> will set the gap to 1. ESC will abort. At the "Stop value?" prompt enter the highest value you want to be assigned to any cluster in the sequence. If this value is reached before the last cluster in the sequence is reached, all remaining clusters in the sequence will be cleared. This is useful if, for example, you want to illuminate all pixels with odd values between 25 and 51. You do not need to calculate how many clusters need to be specified. Specify a large number of clusters, and use the stop value to set 51 as the cut-off. If you press <CR> at the "Stop value?" prompt, the value of stop is set to one less than maxit. If you wish to set the stop value to maxit (or above, which has no effect) you must enter it as a number. I find that I never want to include maxit in the auto-draw sets. I prefer to include maxit in a cluster all its own so that I can easily see the effect of illuminating or darkening just the pixels whose value is equal to maxit, because this can sometimes be a large portion of the screen. After you have answered the "Stop value?" prompt the screen will be re-drawn to show the new image. You will then be back at the Threshview "Cluster?" prompt. As before, pressing <BS> during the re-draw process will halt the re- draw so you may alter more clusters without waiting. -------------------------------------------------------------------- USING GRID Press ^G from main mode, or press G <CR> from Threshview mode to enter Grid mode. Use Grid mode when you want to mark a portion of the current frame to be enlarged in a future frame. When you enter Grid mode a pair of cross-hairs will appear centered on the upper left corner of the screen. At the same time, the coordinates and value of that pixel will be shown on the prompt line. The letter "g" or "s" at the left of the prompt line will tell you whether you are in "glide" or "step" mode. The NumLock on your keyboard will be engaged automatically. Use the number pad keys to move the position of the cross-hairs. Even if you have separate arrow keys, use the number pad keys anyway. Grid actually responds to numbers. This is so that there may be 8 directions plus stop, rather than just 4 directions. The 5 key is stop. The other number pad keys move the cross-hairs. The state of the glide toggle determines whether motion commands operate as single-step or as continuous motion. The Del key toggles glide on and off. The + (plus) key increments step size by one. The * (asterisk) key increments the step size by ten. The - (minus) key decrements the step size by one. The <BS> key sets the step size back to one. Use the above commands to place the cross-hairs at the top and left of the portion of the frame you wish to enlarge. The box commands are all control keys. (Meaning that you hold down the CONTROL key while you tap the indicated key. Control keys are indicated with a carat: ^.) Press ^B to make a box bigger. Press ^S to make a box smaller. These two commands have a built-in scale factor that keeps the box the same shape as the full screen, providing that you avoid the following commands. Use the following only if you want to depart from the default aspect ratio of .75. Press ^D to move the floor of the box downward. Press ^U to move the floor of the box upward. Press ^R to move the right side of the box to the right. Press ^L to move the right side of the box to the left. You may close the box by pressing 0 (zero). Or you may close it by pressing ^S enough times, or by pressing ^L and ^U enough times. You cannot "invert" the box. But if you make a box that has width but no height, or height but no width, one line of the original cross-hairs will disappear. Don't worry about it. The cross-hairs will re-appear once you have opened both height and width to the box, or when you have closed the box. If a box is open, the commands for cross-hair movement will move the entire box, though it will move more slowly. Once you have positioned the box exactly over the portion of the frame that you wish to enlarge, press the # (crosshatch) key. The program will then ask you for a file name. This is to be the name of the data file that will hold the data for the new run. This allows you to use a descriptive file name. If you just press <CR> then Emandel will construct a file name at run-time. Next, Grid will ask you for maxit. This is the value of maxit that will be used for the new frame. If you press just <CR> the present value of maxit will be used. Next Grid will ask you for size. This is the fraction of screen area which is to be used by the new frame. Size must be greater than zero and less than or equal to one. If you select a size that is too large for your computer's memory, Emandel will reduce it at run-time. If you press just <CR> size will be 1. Grid will not ask you for the aspect ratio, because that is determined by the shape of the box you have drawn. This is why, if you want the picture to fill the entire screen, you should avoid the ^R, ^L, ^D, and ^U commands, which change the shape of the box, and use only the ^B and ^S commands which have a built-in .75 aspect ratio. If the aspect ratio of the box is other than .75 then the maximum possible value of size will be less than 1. For example, a square box cannot entirely fill the rectangular screen. If you give a value of size that cannot be met for this reason, Emandel will merely make the frame as large as it can fit into the screen without changing the shape of the box. Thus you can always safely give a value of 1 for the size when you want the largest possible size, even though you might actually get a smaller size. After you have answered the "Size?" prompt, Grid will write a batch file to the currently logged directory. The name of the batch file will be constructed so as not to conflict with any file presently on the same directory. Grid will display the name of the batch file. At this point, you may continue with Grid. You can make as many batch files as you like. Or you may press ESC to exit from Grid mode. You will be placed back wherever you were when you entered Grid mode, either Threshview mode or main mode. Later, after you have exited from Emandel, and you wish to begin work on the frame you marked out under Grid mode above, simply type the name of the batch file (without the .BAT extension) at the normal DOS prompt, just as you would run any program. The batch file will run Emandel with all the command line parameters needed to create the frame you marked out. Because it is assumed that you will have no need for the same batch file a second time, the batch file will automatically erase itself if and only if Emandel exits without any error conditions. If Emandel is unable to start properly (for example if there is not enough RAM or not enough disk space available) then the batch file will not be erased. If you know that you want to keep a copy of the batch file, then either make a backup copy of it, or edit it to remove the second line. Alternatively, if you exit the program using the command ^E^C the batch file will not erase itself. (See ^E under MAIN COMMANDS above.) ------------------------------------------- MOVING FROM MANDELBROT TO JULIA Another feature of Grid mode allows you to create a batch file from Emandel to run Ejulia. Because it is critical when starting Ejulia to have precise control over the selection of the "Julia point", Grid performs this service for you: If you press ^J from Grid mode, Emandel will create a batch file as above. However, it will be a batch file that will run Ejulia, and the Julia point will be the point where the cross-hairs are located. If a grid box is open it will have no effect. The upper left corner of the box is the point that is used. This batch file will run Ejulia with a frame that should enclose the entire Julia set. I recommend setting size fairly small for a quick run, and then using Ejulia to magnify the whole set or parts of the set. (The ^J command has no effect in Ejulia.) Ejulia works just like Emandel, except that a few commands are relevant to one program and not the other. When you use Grid mode in Ejulia, the Julia point written to the batch files is the same as the Julia point in the present run. If you want to change the Julia point you must edit the batch file with a text editor. I do not recommend this, because the outcome is utterly unpredictable. ------------------------------------------- SUBDIRECTORIES Emandel always writes files (data files, picture files, and batch files) to the currently logged subdirectory. By using the ^L command in main or the L <CR> command in Threshview or the L command in Grid mode, you can change the logged drive or subdirectory. Giving an invalid subdirectory name has no effect. But logging on to a drive that has no disk in it will crash the system because DOS will abort the program without returning the HGA to text mode. ------------------------------------------- ESCAPE TO DOS Some programs let you perform DOS commands, or even run entire programs, without exiting the present program. You cannot do this with Emandel because Emandel uses ALL your computer's memory, up to the full 640K DOS limit. There is simply no memory available for anything else while Emandel is running. ------------------------------------------- EXIT CODES Emandel provides exit codes to DOS when it terminates. If you run Emandel from your own batch files, or under the control of some other program that needs to know whether Emandel terminated successfully, you can test for the exit code. The codes are as follows: 0 No errors. Normal program termination 1 Unrecognized command line option. 2 Incorrect number of command line parameters. 3 Insufficient RAM to allocate the data array. 4 Insufficient disk space to hold a completed data file. 5 Emandel cannot find the data file named on the command line. 6 The data file named on the command line comes from the wrong program: Emandel and Ejulia produce incompatible files. 7 Limits error. 8 Size/aspect error. 9 Insufficient RAM to even begin allocating memory for Emandel's internal arrays. 10 Invalid file name on command line. 99 No errors. Normal program termination, but the user has requested a non- zero exit code. ------------------------------------------- ERROR MESSAGES ABORTED. PRESS ANY KEY. An operation has been aborted, probably due to an invalid parameter. Simply proceed with the program. Try the same operation again if you like, being careful to enter valid parameters. CAN'T MAKE BATCH FILE. Emandel is unable to open a disk file. Your disk may be full, (or have no remaining directory space if you are on the root directory). Log on to another drive, or directory, using the ^L or L command and try again. CANNOT GET FILENO. If this occurs it is probably a software error. CAN'T OPEN FILE. Emandel is unable to open a file. Try another disk drive or subdirectory. INCORRECT NUMBER OF ARGUMENTS. You invoked Emandel without the correct number of command line parameters. Read the section of this manual on starting Emandel and try again. INSUFFICIENT DISK SPACE. The presently logged disk drive does not have enough space for the file you are trying to save. Log onto another drive and try again. INSUFFICIENT MEMORY. REDUCING FRAME SIZE. PROCEED OR ABORT? This message will appear if the command line parameters would require Emandel to use more memory than is available in your computer. This is not a fatal error. Emandel will automatically re-size the frame by cutting off as much as necessary from the right-hand side and give you the choice of proceeding or aborting. If you prefer not to have the screen automatically re-sized (which has the side- effect of altering its shape) you may abort and invoke the program again with a smaller value of the size parameter. Unlike automatic re-sizing, changing size on the command line does not affect the aspect ratio. If you have memory- resident programs loaded, they may be taking up a good deal of valuable memory. I recommend you run Emandel without memory-resident programs. MEMORY RESIDENT PROGRAMS PROBABLY WILL NOT WORK WITH EMANDEL, BECAUSE EMANDEL RUNS IN GRAPHICS MODE. If you invoked Emandel via a batch file created in Grid mode and you get this message, pressing "A" for abort will not erase the batch file. You may edit the batch file (setting size smaller) or eliminate memory- hogging memory-resident programs, and try again. INSUFFICIENT SPACE FOR ... BYTE DATA FILE. As a safety measure, Emandel will not start unless there is enough space on the currently logged drive for the full data file that would result on completion. If you get this message, log onto a large enough drive and try again. For reasons of disk access speed, and the large size of Emandel disk files, Emandel should always be run from a hard disk or a very large RAM disk. INSUFFICIENT SPACE FOR ... BYTE FILE. Similar to the above, but this message appears when you try to save a data file, rather than when you start the program. This message does not kill the program. If you see this message, log onto a drive with enough free space and try again. LIMITS ERROR. This is a software error. You should never see this one. If you do, it is a program bug. Please let me know. NO RAM AVAILABLE. This message appears at program start-up (and the program aborts) if there is not even enough memory to *begin* to allocate Emandel's memory requirements. This is very unlikely. It may mean that you have very little memory, or a *lot* of memory-resident programs. If you know that you have 384K or more, try doing a cold-boot and trying again. Try booting without any memory-resident programs. SIZE/ASPECT ERROR. This is another software bug error. If you see it, please let me know. <file> NOT AN EMANDEL FILE <file> NOT AN EJULIA FILE These messages mean the file passed to the program on the command line is of an incompatible type. Emandel and Ejulia files are not interchangeable. UNRECOGNIZED OPTION. This message means that there was an option on the command line that Emandel does not recognize. Please read the section on starting Emandel and try again. -------------------------------------------------------------------- EMDISPLAY Emdisplay allows you to view and print pictures created with Emandel. Note that Emdisplay does not view data files (with the PIK file type extension) but only PICTURE files (which you create with Threshview and which have the PIC file type extension.) USAGE: EMDISPLAY [<filename>] [...] [/<options>] <filename> is any valid file name, optionally including a drive designation and path. It may contain MS-DOS "wild cards". If no file type extension is given, then PIC is assumed. You may list as many different file names as you like, each of which may contain drive\path and wild cards. If no file name is given, then *.PIC is assumed. /<options> are optional. The options all deal with printing, so you need not use them if you are going to view files without printing. The list of options must be preceded by a forward slash, and there must be no spaces after the slash or within the list of options. Available options are as follows: (They may be used in any order and letters may be upper or lower case.) 2 Use port LPT2. 3 Use port LPT3. ? Print a help message. This option also aborts the program, so it makes the other options superfluous. D Print dark. This is useful if your printer ribbon is not as dark as you want. Basically this command is an "overstrike" mode. F+ Increase the amount of the line feed by 1/216 of an inch. You may want to use this if your printer does not track well. F- Decrease the amount of the line feed by 1/216 of an inch. N Print without asking. Normally Emdisplay shows you the pictures one at a time and waits for you to press a key. If you include N in the options, Emdisplay will print all the pictures without pausing. Thus, if you use fanfold paper you can print a number of pictures unattended. If you use this option, Emdisplay will exit after all the files in the list have been printed. R Print the picture so that black and white are reversed. Z Send the print output to a disk file named EPT.DAT instead of to the printer. This is really intended as a diagnostic feature. But it also allows you to create a data file that can drive the printer independent of the Emdisplay program. ^ (carat) This command over-rides the automatic paper advance. Normally, if you place the paper so that its top edge is even with the top of the ribbon, Emdisplay will advance the paper so that the finished picture is centered in the page. However, with this command you can over-ride that feature. COMMANDS FOR USE WITHIN EMDISPLAY Emdisplay shows you the pictures you listed on the command line and at each picture it waits for a command, unless you included N in the options. (See above.) The commands are: LEFT ARROW or UP ARROW or B Emdisplay will go back to the previous picture. HOME Go back to the first picture. END Go to the last picture. P Print the picture. Emdisplay will use printer port LPT1 unless you have included 2 or 3 in the options list, in which case it will use LPT2 or LPT3 respectively. After printing it will automatically advance to the next picture in the list. ALT-P Print dark if /D was NOT specified on the command line, or print light if /D WAS specified on the command line. In other words, this command prints the file but over-rides the command-line intensity specification. X Emdisplay will quit and exit. ESC Same as above. <any other key> Emdisplay will go forward and show you the next picture. ^C If you press control-C while Emdisplay is printing a picture, the printing will abort and the program will advance to the next picture. The printer will not immediately stop because it already has the next few lines in its own internal memory buffer. If you press control-C when Emdisplay is not printing, it has the same effect as Q above. The pictures are viewed in a continuous loop. After the last, it returns to the first. If you go (B)ackward from the first, it shows you the last. It will not terminate until you tell it to unless you use the N option (print without asking, see above). When you tell Emdisplay to print a picture, it first advances the paper, unless you have used the ^ option. (See above.) This makes it easier to position the paper: Put it so the top of the page is level with the top of the ribbon. At the end of printing a picture, Emdisplay sends a form-feed to the printer. Thus, if you are using fan-fold paper you can print a number of pictures one after the other, and they should all be centered correctly. (However, on my printer, friction feed is more accurate than tractor feed, so pictures printed on individual sheets look better than those printed on fan- fold paper.) Pictures are printed sideways, so a wide-carriage printer is not required. ERROR MESSAGES You may get an error message when you try to print, or during printing if your printer is turned off, if it is off-line, if there is no printer connected to the printer port, if it runs out of paper, or if you shut it off while printing. If this happens, Emdisplay will give you a choice: (A)bort, e(X)it, (R)etry? If you press A the attempt to print the current picture will be abandoned. You may tend to you your printer and try again. If you press X the program will terminate and exit. If you press R the program will try to continue where it left off when the error occurred. -------------------------------------------------------------------- FILE FORMATS In case you wish to make use of Emandel's files for programs of your own (perhaps to write your own printer driver for a non-Epson printer) I provide below the file formats. DATA FILE FORMAT The data files always have the file type extension PIK. The first byte is an ascii character: K for Emandel, and J for Ejulia. Future versions may use different characters to allow detection of incompatible file formats. The next 80 bytes are program variables. (I)ntegers are 2 bytes, (D)oubles are 8-bytes in standard 8087 format, (L)ong integers are 4 bytes. The variables appear in the following order: (D) The real component of the left edge of the frame. (D) The imaginary component of the top of the frame. (I) The width in pixels of the frame. (I) The height in pixels of the frame. (I) The width the data array. (I) The height the data array. (D) The increment between calculated points. (D) The height to width aspect ratio. (D) The fraction of the screen covered by the frame. (I) The iteration cut-off limit, maxit. (I) The number of vertical scan lines completed so far. (D) The imaginary component of the bottom of the frame. (D) The real component of the Julia point. (0.0 in Emandel.) (D) The imaginary component of the Julia point. (0.0 in Emandel) (L) The number of seconds spent so far in calculation phase. The next 44 bytes are filler, to allow header room for future versions. The rest of the file is the iteration value of the pixels. Pixels are mapped from the top of the frame to the bottom, and then from left to right. If maxit is less than or equal to 255 then each pixel takes one byte. If maxit is greater than 255 then each pixel takes 10 bits. "The height of the data array" above is the number of bytes per vertical scan line in the data file if maxit is less than or equal to 255. If maxit is greater than 255, then add 25% to the height to get the number of bytes per vertical scan line. "The number of vertical scan lines completed so far" is the number of vertical scan lines in the data file. PICTURE FILE FORMAT Picture (image-only) files always have the file type extension PIC. The file begins in ascii with the command line that started Emandel, terminated with decimal 26, and then filled out to a standard total length of 160 bytes. This allows Emandel to re-create an old data file from the picture file. If you have made the data file MYPIC.PIK and made a picture from it named MYPIC0.PIC and then erased the date file MYPIC.PIK to save disk space (the picture file is about 1/10 the size of the data file) and then you want to re-create the original data file, do the following: COPY /A MYPIC.PIK DOIT.BAT DOIT The DOIT batch file will run Emandel for you. After those first 160 bytes: The next 2 bytes are an integer, the HEIGHT in pixels of the frame. The next 2 bytes are an integer, the WIDTH of the frame in pixels. Then follows the body of the data: Pixels are bit-mapped from the picture frame to the file one horizontal scan line at a time. The length of each scan line in bytes is one-eighth of the WIDTH above. The number of scan lines is equal to HEIGHT, above. Note that this is not a simple dump of the HGA memory. The HGA mixes up the order of the scan lines, which Emandel does not do. One-third of the scan lines are reserved for the printer and do not show on the screen. The height and width of the file are only as large as required for the picture. Thus small pictures make small files. Following image data is the title line, also bit-mapped, as eight scan lines, each 84 bytes long. Although Emandel shows small-size frames in the upper left corner of the screen, Emdisplay will center images in the screen and place the title line at the bottom. Although small frame sizes make smaller data and picture files, Emandel does not use data compression. If you are saving a lot of files, I recommend the use of a file archiving program such as PKARC, from PKWARE. PKARC is shareware and is available from many sources, including BBS systems. -------------------------------------------------------------------- A NOTE ON MAXIT For the overview of the entire Mandelbrot set you can set maxit to 100. As you go to larger magnification, you will often need to set maxit higher in order to get satisfactory results. Generally, the higher you set maxit, the longer it will take to complete the frame. You will soon learn to get a balance between these two concerns. ------------------------------------------- GLOSSARY OF SOME TERMS USED IN THIS DOCUMENTATION ASPECT RATIO The ratio of height to width. Because of the extra scan lines kept out of sight in Emandel's memory, the aspect ratio you see on the screen is the same as you will get on the printer. CLUSTER In Threshview mode (and its offshoot, Auto-draw) a cluster holds a range of pixel values to be illuminated. In the present version there are 301 clusters, numbered from 0 to 300. A cluster may be clear, in which case it has no effect. Or it may have a bottom and top value. Any pixel whose value is within any cluster will be illuminated. Thus if a cluster is assigned a bottom of 17 and a top of 19, then all pixels with values of 17, 18, or 19 will be illuminated. Thus you can define up to 301 different ranges of values, and all pixels that fall inside of any of these ranges will be illuminated. It is this flexibility that gives Emandel its character: It lets you interact with the computer to specify the values to be illuminated. You become an artist, and your material is the raw data produced by the program. (Incidentally, the quantity of data in one typical run of Emandel would have taken a mathematician with paper and pencil several lifetimes to produce in the days before computers.) CLUSTER BOTTOM The bottom value in a cluster: the minimum pixel value that will be illuminated by that cluster. CLUSTER SIZE The difference between the cluster bottom and the cluster top, plus one. Thus if bottom is 17 and top is 19, the size of the cluster is 3. When Auto-draw asks you for size, it wants to know the size of each cluster in the sequence that is to be set automatically. CLUSTER STOP VALUE In Auto-draw, this is a cut-off value. If you have specified a range of clusters to be set automatically, Emandel assigns bottom and top values to them in ascending order. If the stop value is reached before the last cluster is reached, the remainder of the clusters in the sequence will be cleared. Thus you actually have two ways of specifying the upper cut- off: by the assignment of "last cluster" or by the assignment of "stop value". CLUSTER TOP The top value in a cluster. The maximum pixel value that will be illuminated by that cluster. DATA FILE The disk file in which Emandel stores all the information needed to resume a run which has been halted. Eventually, this is the data that Emandel will use to make images in Threshview mode. EXIT CODE When a program running under MS-DOS terminates, it can give DOS a number, called an exit code. It is often useful for a program to communicate with DOS to announce whether it did its job and terminated normally, or encountered an error condition and was forced to abort without doing its job. This exit code can be tested in a batch file, or can be read by the next program. See EXIT CODES elsewhere in this documentation. FIRST CLUSTER When auto-draw asks you for a first cluster, it wants to know the first of the sequence of clusters that you wish to set automatically. FRAME The frame is the portion of the complex number plane being examined. GAP In auto-draw, GAP is the difference between the top of one cluster and the bottom of the next. GLIDE In Grid mode, glide means that cross-hair motion commands are "sticky": they continue until you override them with another command. The <Del> key toggles glide mode to step mode. GRID BOX The grid box is the portion of the screen marked out by the two sets of cross-hairs in Grid mode. GRID MODE Grid mode is the feature of Emandel that lets you see the coordinates and value of any pixel and create batch files automatically. This makes it much easier to explore the Mandelbrot set than it would be if you had to guess at the coordinates of the areas you wanted to view. GRID WINDOW Grid window is another term for Grid box. HEIGHT The number of scan lines in Emandel's internal memory array. It can be slightly larger than y-limit because it must be divisible by 4. Both height and y-limit are larger than the height in pixels of the screen image because of the extra scan lines for the printer. LAST CLUSTER When Auto-draw asks you for the last cluster, it means the last in the sequence of clusters you wish to set automatically. MAXIT This is the maximum number of iterations that will be performed on any one pixel during calculation phase. For most frames, setting maxit lower will result in faster calculation, but setting maxit higher will result in more clearly-defined edges. Generally, I advise setting maxit low for broad over- views of the set, and setting maxit high for highly-magnified views of structures very near the edge of the set. (Note that it is never possible to determine ABSOLUTELY the boundary of the Mandelbrot set. All you get is an approximation. Setting maxit higher increases the accuracy of the approximation.) The highest you can set maxit is 1023 because of memory limits. PICTURE FILE This is the disk file that holds a picture created in Threshview mode. Because it holds only the image, and not the full data, it is much smaller than the full data file. A picture file for a full size picture is 43K. (About one-tenth the size of a full data file.) PIXEL Stands for "picture element" and is one dot on the screen, or on the printed picture. On the HGA there are 250,560 pixels. Emandel only uses 228,480 of those for screen images. But it uses 338,688 pixels for printed pictures. SET A set really just means a bunch of things. The Mandelbrot set is the collection of points on the complex number plane that fit the criterion described elsewhere in this document. SIZE This refers to the fraction of the screen area that will be covered by the frame. The aspect ratio takes precedence and sets an upper limit to SIZE. Setting SIZE smaller allows you to reduce the size of the picture and thereby shorten the calculation time. START VALUE When Auto-draw asks you for a start value, it means the bottom value for the first cluster in the sequence of clusters to be set automatically. STEP In Grid, step mode means that cross-hair movement commands are single- step. <Del> toggles step mode to glide mode. THRESHVIEW MODE Threshview mode is the feature of Emandel that allows you to interactively create pictures. You can become a regular Van Gogh. The keyboard is your brush, the screen your canvas, and the raw data is your paint. WIDTH The width in pixels of Emandel's memory array. This can be larger than x-limit because it must end on a byte boundary. X-LIMIT This is the width in pixels of the actual picture frame. Y-LIMIT This is the height in pixels of the Emandel picture as it will appear on the printer. It is 50% greater than the height in pixels of the picture on the screen. -------------------------------------------------------------------- KITTENSOFT ABSOLUTE UNCONDITIONAL NO-BUGS GUARANTEE: I give you my absolute unconditional guarantee that I will be surprised if there are no bugs in these programs. I *hope* that I have eliminated *most* of the bugs. I hope you enjoy these programs. Dan Schechter Route 1 Box 19 Amenia, North Dakota 58004 U.S.A.